<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html version="4.01"><head><title>[retawq] Reporting Problems</title></head>
<body text="#000000" bgcolor="#cccccc" link="#0000ff" vlink="#551a8b"
alink="#551a8b" lang="en">
<center><b><font size="+2">retawq Documentation</font><br><font
size="+1">Reporting Problems</font></b></center>

<p>This page describes how to report a problem you found when using retawq.
Before you write a report, please make sure that you use the most recent
version of retawq which is available on the project home page and that the
problem does not occur with other web browsers. To report a bug or other
problem, you can send an e-mail to the <a
href="mailto:arne@arne-thomassen.de">maintainer</a>. Your report should include
at least the following information:</p>

<ul>
<li>a short, precise description of the problem</li>
<li>the version of retawq you use</li>
<li>operating system, possibly relevant libraries, C compiler</li>
<li>if compiling/linking failed: the complete, verbatim error messages</li>
<li>if the problem might be related to (or might depend on) the <a
href="ctconfig.html">compile-time configuration</a>: the file ".config" which
was generated by the configure script resp. by "make"; if you don't have this
file anymore: the output of a shell command like "retawq
--dump=about:ctconfig"</li>
<li>if the problem might be related to (or might depend on) the <a
href="rtconfig.html">run-time configuration</a>: the file
/home/<i>your_home</i>/.retawq/config or the relevant parts from it and the
built-in run-time configuration (if any; cf. the <a
href="ctconfig.html">compile-time configuration option</a> OPTION_BIRTCFG);
please make sure that you don't send passwords</li>
</ul>

<p>Some parts of this information can be collected by simply running
"./configure --report" (if you use the configure script) resp. "make report"
(if you use the classical Makefile).</p>

<p><a name="debug"></a><b>Debugging Mode</b></p>

<p>When a problem can't be solved otherwise, you might want to enable retawq's
debugging mode to find out whether the resulting debugging messages show the
cause of the problem. The debugging mode is realized by the special, internal
compile-time configuration option CONFIG_DEBUG. To enable it, do the
following:</p>

<ul>
<li>if you use the configure script: run the script as usual; then open the
file ".config" (which was generated by the script) with a text editor and
change the value of CONFIG_DEBUG from 0 to 1</li>
<li>if you use the "classical" Makefile: open the Makefile in a text editor and
change the value of CONFIG_DEBUG from 0 to 1</li>
<li>run "make" to build the program</li>
</ul>

<p>The resulting program generates a file called "debug.txt" in the current
directory. Old contents of this file are overwritten whenever the program is
started. The file contains lots of cryptic debugging messages, most of which
aren't related to a particular problem. Please note that the file might also
contain passwords (e.g. from the <a href="rtconfig.html">run-time
configuration</a> handling) or confidential documents (e.g. when you received
something via <a href="tls.html">TLS/SSL</a>). So you should remove old
debugging files as soon as you don't need them anymore, and you should remove
any passwords and other confidential stuff from the file or replace them with
"[snipped]" markers or similar before sending the file.</p>

<p>Enabling the debugging mode has many more consequences than just the
generation of the debugging file. For example, the program becomes bigger and
slower, it might create an HTML parser debugging file ("htmldebug.txt"), and
the status line at the bottom of the screen shows cryptic additional
information. In short: use this mode only if necessary; it's only intended to
solve problems which can't be solved otherwise.</p>

<p><a name="gdb"></a><b>Debugging with gdb</b></p>

<p>If retawq crashes, it's very useful to find out where exactly the crash
happened. A debugger catches the crash and allows you to get the information.
The following description shows how to do this with GNU <a
href="http://directory.fsf.org/gdb.html">gdb</a>, but much of it applies to any
debugger similarly.</p>

<ul>
<li>If you use the configure script: make sure that LDFLAGS doesn't contain the
option "-s" which would cause important symbols to be deleted from the binary.
For example, run the configure script like so: "./configure LDFLAGS=' '". (That
is, set the LDFLAGS to a "dummy" space character.) After this, build the
program with "make".</li>
<li>If you use the "classical" Makefile: use "make devel" instead of "make", or
remove the target "stripsyms" from the "build_binary" line.</li>
<li>Start the debugger: "gdb ./retawq".</li>
<li>Start retawq: at the debugger prompt, enter "run".</li>
<li>Now try to reproduce the crash. The debugger will catch it.</li>
<li>At the debugger prompt, enter "bt" to get a stack backtrace. That's the
interesting information. The easiest way is to get it verbatim with some mouse
copy-pasting; you might have to toggle retawq's mouse handling mode with the
keyboard command "Y" before crashing the program.</li>
</ul>

<p>Independently, the output of a "strace" command can also be useful and might
be easier to get.</p>

<p><hr>This documentation file is part of version 0.2.6c of <a
href="http://retawq.sourceforge.net/">retawq</a>, a network client created by
<span lang="de">Arne Thoma&szlig;en</span>. retawq is basically released under
certain versions of the GNU General Public License and WITHOUT ANY WARRANTY.
Copyright (C) 2001-2006 <a href="mailto:arne@arne-thomassen.de"><span
lang="de">Arne Thoma&szlig;en</span></a>.</p>
</body></html>
